Gegevensoverdracht

SOAP-webservices worden gebruikt om transactiegegevens te verzenden tussen het hostsysteem en Vocollect VoiceCheck. VoiceCheck ondersteunt zowel SOAP- als REST- webservices. Deze services bieden de import- en exportfunctionaliteit voor het VoiceCheck-systeem.

De indelingen van de services en berichten zijn hieronder in detail beschreven, en referentie-XML voor de SOAP Web Service Description Language (WSDL) en REST Web Application Description Language (WADL) zijn meegeleverd in de productverpakking. Beschrijvingen van de services waren vroeger in te zien door http://<host>:<poort>/VoiceCheck/services/api/swagger.json in te voeren in uw webbrowser. Deze koppeling vervangt de eerder gebruikte koppeling http://<host>:<poort>/VoiceCheck/services.

Berichtenstroom webservices

Configuratie en beveiliging

Het hangt van de VoiceCheck-configuratie af of alle communicatie over HTTP of HTTPS wordt uitgevoerd.

Voor gegevensimport vereisen alle SOAP-webservices die door VoiceCheck worden verstrekt verificatie met WS-Security UsernameToken. Alle REST-webservices voor importer vereisen verificatie met HTTP-basisverificatie.

VoiceCheck heeft een toegangsrol, configureerbaar in de gebruikersinterface, die de machtigingen van een gebruiker bepaalt voor het uitvoeren van webservices. Het hostsysteem van webserviceclients moet worden geconfigureerd om te verifiëren met VoiceCheck-webservices als een gebruiker met deze rol.

Voor gegevensexport ondersteunt VoiceCheck het gebruik van HTTP-basisverificatie voor toegang tot SOAP- of REST-webservice op het hostsysteem. Verificatie is optioneel, maar als deze wordt toegepast, wordt dat geconfigureerd in VoiceCheck, en het wachtwoord wordt versleuteld en opgeslagen in de VoiceCheck-database.

Ook biedt VoiceCheck een methode om de URL voor het service-eindpunt te configureren voor services die het hostsysteem biedt. Deze eindpunt-URL is een verplichte instelling in de GUI.

Er wordt maar één gebruikersnaam en wachtwoord gebruikt voor alle services die het hostsysteem weergeeft voor VoiceCheck. Er wordt momenteel maar één service weergegeven voor VoiceCheck om toewijzingsresultaten te posten in het hostsysteem.

De configuratiegegevens (service-eindpunt, type client webservice, gebruikersnaam en wachtwoord) worden ingesteld op systeemniveau in VoiceCheck. U kunt deze instellingen vinden op de pagina Beheer > Systeemconfiguratie. De configuratie gaat ervan uit dat één exemplaar van VoiceCheck verbinding zal maken met één eindpunt van het hostsysteem.

XML-schema's en naamruimten

VoiceCheck declareert een naamruimte voor alle XML-elementen die in SOAP- en REST-services worden gebruikt, met uitzondering van het element faultInfo (zie de onderstaande opmerking). De naamruimte is:

http://service.web.voicecheck.vocollect.com/

Voor SOAP-services die VoiceCheck biedt voor gegevensimport, kunt u de naamruimte en het schema vinden in de WSDL.

Voor REST-services die VoiceCheck biedt voor gegevensimport, kunt u de naamruimte en het schema vinden in de WADL. Merk op dat voor de webservice Toewijzing maken REST-clients de XML met de naamruimte niet hoeven te kwalificeren; het wordt echter wel sterk aangeraden.

Voor de REST-service die VoiceCheck gebruikt om toewijzingsresultaten te posten in een hostsysteem, wordt de naamruimte en het schema dat de server verwacht te zien in de XML gedefinieerd in de voorbeeld-WADL die in het pakket is meegeleverd.

Het element faultInfo is niet gedefinieerd als onderdeel van een naamruimte. Voor REST-services kwalificeert VoiceCheck het element met een naamruimte niet wanneer het dit verzendt in een foutmelding naar een hostsysteem. Ook mag het hostsysteen geen faultInfo-element met een naamruimte kwalificeren in een reactie opVoiceCheck .

Foutverwerking voor toewijzingsgegevens

REST-foutverwerking

Als er een fout optreedt, kunnen diverse HTTP-statuscodes worden geretourneerd. Dit hangt af van de fout en waar de fout tijdens verwerking optrad. VoiceCheckmaakt gebruik van het CXF-framework Apache^® voor het verwerken van aanvragen van webservices. Het framework kan fouten zoals 406 – Niet geaccepteerd, of 415 – Geen ondersteuning voor mediatype retourneren, voordat de VoiceCheck-bedrijfslogica is bereikt.

Fouten die uit de VoiceCheck-bedrijfslogica komen, hebben een van deze twee statuscodes:

• 400 – De client heeft een bedrijfsregel of -beperking geschonden (gewoonlijk beschadigde gegevens). Het bericht opnieuw verzenden zonder de inhoud te wijzigen, resulteert in dezelfde fout.
• 500 – Er is een interne serverfout opgetreden tijdens de verwerking van de aanvraag. Het bericht opnieuw verzenden KAN helpen.

Ook bevatten fouten die uit de VoiceCheck-bedrijfslogica komen een faultInfo-XML-element met meer informatie over de fout die optrad. De eigenschappen van het faultInfo-element zijn hieronder vermeld.

SOAP-foutverwerking

SOAP 1.1-fouten worden voor alle fouten geretourneerd. Alle fouten bevatten een foutcode en fouttekenreeks in overeenstemming met de specificatie in SOAP 1.1. Twee van de SOAP 1.1-kernfoutcodes, Client en Server, worden voor de meeste fouten vermeld. VoiceCheckgebruikt deze codes gewoonlijk op de manier die is beschreven in de SOAP 1.1-specificatie.

Er zijn fouten die op kunnen treden tijden verificatie met foutcodes die zijn gespecificeerd in WS-beveiliging (webservicebeveiliging). API's en implementaties van de Java-webservices kunnen andere foutcodes retourneren.

Hoewel we onmogelijk alle voorkomende foutcodes kunnen vermelden, zijn er algemene regels die consistente afhandeling van fouten door webserviceclients mogelijk maken:

• Andere foutcodes dan Server-foutcodes betekenen in het algemeen dat het geen zin heeft om het bericht nogmaals te verzenden. Ze worden verzonden als de client iets verkeerd heeft gedaan, voordat de overdracht de toepassingslogica op de server heeft bereikt, zoals verificatiefouten of berichten met een ongeldige indeling.
• Fouten met de foutcode Server komen uit de serverlogica van de toepassing, en bevatten het SOAP 1.1-foutdetailelement. De indeling wordt gespecificeerd in de WSDL, maar bevat de informatie in het onderdeel hieronder.

Het element Foutinfo

Zowel REST- als SOAP-webservices bevatten dezelfde foutinformatie als een fout uit de serverlogica van de VoiceCheck-toepassing komt.

De REST-implementatie van de hostserver voor het posten van toewijzingsresultaten moet dit foutinfo-element gebruiken om de foutmelding in de VoiceCheck-GUI te gebruiken, anders ziet de gebruiker een algemene melding.

Eigenschap	Typen	Definitie
Foutcode	lang	Numerieke code voor de fout. Geldige waarden: 3000 = Interne serverfout (aanvraag kan maar hoeft niet te lukken bij een nieuwe poging) 3001 = Ongeldige aanvraag (automatisch nogmaals proberen wordt afgeraden)
bericht	tekenreeks	Een voor mensen leesbaar bericht waarin de fout wordt uitgelegd.